-
Notifications
You must be signed in to change notification settings - Fork 961
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Initial "wireframe" for model contracts #2890
Conversation
* placeholder outline * add version blocks * add to sidebar * remove version blocks * add 2 sections * postgres section example * add more docs * correct DDL * correct config name * fix data type * add redshift docs * Update constraints docs for Snowflake * add model config links * update warehouse to spark * update not null syntax * add more config examples * fix ordering * update docs based on new parsing * add a note * add example error messages * Update config name on Redshift * Update description for Spark * add explainers * add check * remove fluff --------- Co-authored-by: Dave Connors <dave.connors@fishtownanalytics.com> Co-authored-by: Benoit Perigaud <8754100+b-per@users.noreply.github.com>
✅ Deploy Preview for docs-getdbt-com ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
"page": "reference/dbt-jinja-functions/local-md5", | ||
"firstVersion": "1.4", | ||
}, | ||
{ | ||
"page": "reference/warehouse-setups/fal-setup", | ||
"firstVersion": "1.3", | ||
}, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No functional change here, I just reordered the list so it's in a consistent (descending) order by firstVersion
. I figure, in the future, we could remove items from this list as we deprecate older versions.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you!
Co-authored-by: Doug Beatty <44704949+dbeatty10@users.noreply.github.com>
I wanted to note two particular editorial changes in case others have strong feelings about them: |
Smart to prepare for translation, @matthewshaver 🧠 It is feeling awkward to me when reading "prerequisite check" in context currently. Is there an option to re-phrase this in a way that simultaneously prepares for translation and reads more smoothly? |
@matthewshaver @dbeatty10 Love that we're having this conversation! I will say that "parameters" and "prerequisites" don't feel quite right. Let's find the right words, both to capture the meaning and to enable eventual translation into other languages! Parameters feels much too vague of a term. A "parameter" could be any model attribute/property/configuration, and it doesn't carry the same force of consistent truth. What I'm after here is, a set of things that are guaranteed to be true about the structure of this model and the dataset it produces. They're guaranteed because, if they're found to be untrue, the model doesn't build! "The thing I am telling you will be true, because it cannot be otherwise. Es muss sein. If it must be otherwise, then I must first change the thing that I am telling you." Other words here: "contract" (we're already using this one!), "commitment" around the "shape" or "structure" of the data...? Prerequisite to me implies, a thing the user must do in order to be able to use this feature. There's some truth to that—the user must define the |
I went with "verification" rather than prerequisites. Regarding the contracts, I slipped the word "guarantee" back in and clarified it with "attestations," which might be a more comfortable and broadly understood word in the software world. Let me know if that still doesn't hit right and maybe we can revert to the original form in the interest of shipping. |
We've been using the following to phrases pretty frequently while iterating on contracts:
In the interest of shipping, how would you feel about adding those back in for now with the promise that we'll spend more time re-considering this verbiage before the final 1.5 release? I don't really have a horse in the race for the exact phrasing here. But I do think that we'd get a lot of value out of getting and initial version of these docs published. |
No problem. Plenty of time in the future to have these convos. It's reverted and my review is complete. Ready for merge as soon as you're ready to take it out of draft @jtcohen6 ! |
Thanks for the work on this @matthewshaver @dbeatty10! Plenty of time to have more convos & more rereads/reviews. I'm marking this as "Ready" in the spirit of getting docs live early & often, to accompany our early & often beta prereleases :) |
resolves #2839
resolves #2594 (includes #2601)
waiting on v1.5 initialization (#2842)
What are you changing in this pull request and why?
Opening an early draft PR for discussion!
My goal right now is just to stand up some initial "wireframes" with suggestive/placeholder content. A lot of the language will need refining, and the content will need deduplicating/reorganizing. Our goal is to push up iterative changes early & often, so we can gather regular feedback. I feel good about these pages being:
Specific changes:
contract
&constraints
. These pages will need to be reworked as we rework the functionality & syntax—a good thing! I tried to call out explicitly places where I expect us to come back and edit/update.Checklist
Add a checklist item for anything that needs to happen before this PR is merged, such as "needs technical review" or "change base branch."Adding new pages (delete if not applicable):
website/sidebars.js